home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 151-175 / scopedisk157 / lpatch / lcompare.doc < prev    next >
Text File  |  1995-03-19  |  7KB  |  143 lines
  1.             PTCH IFF Format
  2.  
  3. Copyright (c) 1989 Lattice, Inc.  All Rights Reserved.
  4. Copyright (c) 1990 SAS Institute Inc.  All Rights Reserved
  5.                    SAS Campus Drive
  6.                    Cary NC 27513
  7.  
  8. Address all questions to John Toebes
  9.    Bix:  JTOEBES    Plink: JTOEBES
  10.  
  11.                 
  12. This document describes the PTCH IFF format as implemented by the SAS/C
  13. LCOMPARE and LPATCH programs.  We are making the actual format of this
  14. Patch file public so that others may benefit from its use.
  15.  
  16. SUMMARY
  17. -------
  18. The PTCH IFF format provides a standard method of describing patches
  19. for arbitrary binary (and of course ASCII) data.  The patch format allows
  20. for descriptive text to be included as part of the patch as well as
  21. checksumming information to ensure the validity of the patch.  
  22.  
  23. The PTCH form consists of 5 standard chunks (described in detail below).
  24.  
  25. VERS describes the version of the Patch program necessary to apply
  26.      the patch.
  27. INPF indicates a default input file to be used as well as the attributes
  28.      of that file to prevent patching the wrong file.
  29. OUTF describes a default output file along with the attributes of the
  30.      created file to ensure that the patch applied correctly.
  31. PMSG descibes a string to be output to the terminal when running the patch
  32.      program.  This chunk is optional and may occur more than once.
  33. PSEQ Contains the actual patch instructions.
  34.  
  35. Only the PMSG chunk is optional.  All other chunks are required.
  36.  
  37. VERS
  38. ----
  39.   The VERS chunk contains information describing the revision of the
  40. patch program necessary to apply the patch.  The chunk consists of 4 bytes
  41. followed by a text string.  The first two bytes are reserved for future 
  42. expansion and must always contain 0.  The third byte is the major version
  43. of the patcher program with the minor version being stored in the next (4th)
  44. byte.  At present time, this spec refers to the 3.0 format.  The string
  45. following these 4 bytes is simple ASCII text that may be used to more
  46. completely describe the version.  There is no restriction on the format of
  47. this text.  If it is an odd number of bytes long, it must be padded with
  48. a single trailing null byte to bring the chunk to an even size.
  49.  
  50. INPF
  51. ----
  52.   The INPF chunk describes the input file to be patched.  It consists of
  53. two long words followed by an ASCII string.  The first long word is the
  54. checksum of the input file computed by adding all bytes in the file
  55. and throwing away any overflow beyond 32 bits.  The second longword is the
  56. length of the input file in bytes.  Future version of the patch program
  57. may chose to implement this verification through CRC or other more
  58. sophisticated methods.  If this is done, the VERS chunk should be updated
  59. to reflect this.
  60.  
  61. The ASCII string indicates the default name of the file to be patched.
  62. As with the VERS string, an odd length string is padded out with a single
  63. null byte to bring the chunk to an even size.
  64.  
  65. OUTF
  66. ----
  67.   The OUTF chunk is identical in form to the INPF chunk.  In this case,
  68. the version information is used to verify that the patch was applied
  69. correctly as a final check.
  70.  
  71. PMSG
  72. ----
  73.   The PMSG chunk is a hook to allow a developer to print out special
  74. information about a patch being applied.  More than one PMSG chunk may
  75. be present in the file; each will be printed out in turn.  This can be
  76. useful when you wish to print out a message before the patch is applied
  77. and another after the lengthy patch process has completed.  If the message
  78. is an odd length, it is padded out with a single null byte to bring the
  79. chunk to an even size.
  80.  
  81. PSEQ
  82. ----
  83.   The PSEQ chunk contains the actual patch data to be applied.  This data
  84. consists of a series of single byte commands to indicate the action to
  85. take.  Commands that are in lower case are followed by a single byte
  86. length.  Upper case commands are followed by 2 or 4 bytes of data based
  87. on the command.  However, they can be treated as 2 byte lengths with the
  88. 'C' and 'D' commands treated special.  All lengths are treated as unsigned.
  89.  
  90. With the 3.0 version, the following commands are supported:
  91.    'C' <4 byte Checksum of original> - Simple additive checksum of
  92.        the original program.  This information is somewhat obsolete in that
  93.        is contained in the INPF chunk; hence the LCOMPARE program does not
  94.        output it.
  95.    'D' <4 byte checksum of final program> - Simple additive checksum of the
  96.        generated program.  Like the 'C' command, this is obsoleted by the
  97.        presence of the information in the OUTF chunk and is not output by
  98.        the LCOMPARE program.
  99.  
  100.    'S' <2 byte length> - Skip bytes from original file.
  101.    's' <1 byte length> - Skip bytes from original file.
  102.        Skips over bytes in the input file and in effect does a forward
  103.        seek.  If more than 64K bytes need to be skipped, multiple S
  104.        commands need to be used.  The output file is not modified.
  105.  
  106.    'U' <2 byte length> - Use bytes directly
  107.    'u' <1 byte length> - Use bytes directly
  108.        Copies bytes directly from the original input file at the current
  109.        position to the end of the output file.  If more than 64K bytes of
  110.        data is to be copied, multiple U commands can be used.
  111.  
  112.    'I' <2 byte length> <bytes> - Insert bytes
  113.    'i' <1 byte length> <bytes> - Insert bytes
  114.        Inserts the given data into the output file.  The data bytes are
  115.        taken directly from the patch file for the specified length.  The
  116.        input file seek position is unaffected.  Insertions of more than
  117.        64K must be done with multiple 'I' commands.
  118.        
  119.    'R' <2 byte length> <bytes> - Replace bytes
  120.    'r' <1 byte length> <bytes> - Replace bytes
  121.        Replaces the specified number of bytes in the output file by first
  122.        skipping the specified length in the input file (as with the S
  123.        command) followed by inserting the same number of bytes in the
  124.        output file using the data directly following in the patch file.
  125.        Replaced areas of more than 64K must be done with multiple R
  126.        commands.
  127.  
  128.    0   A filler byte used to pad out the patch data to an even length.  Any
  129.        zero bytes are to be ignored.
  130.  
  131. All other commands are considered illegal and if encountered are to abort
  132. the patch.
  133.  
  134. The choice of 2 bytes for most lengths is based on the observation that few
  135. patches exceed 64K.  For these, it is felt that the extra overhead of a
  136. single byte is well worth the noticable savings for most other patches.
  137. If this is felt to be a burden, additional commands could be quickly added
  138. to remedy the situation.
  139.  
  140. AVAILABILITY
  141. ------------
  142. The LPATCH program as provided by SAS Institute is freely redistributable.
  143.